Filename README.TXT, copyright W. L. Sexauer, November 2, 1991. The XCONTROL program was written to provide a better method of operating the Powerhouse X10 (TM) controller than the software provided with the controller. The principal advantage of this program is that it allows events to be varied with the local sunrise and sunset without the effort of editing files or individually deleting and re-entering events. The XCONTROL program also allows the following additional functions: setting the clock in the controller, setting the base housecode of the controller, deleting a single event from those stored in the controller, loading a complete schedule of events into the controller, loading a single event for execution now, today or tomorrow, or displaying or printing the events stored in the controller. The program is marketed under the shareware concept. You are free to try out the program, and to distribute it to others as long as you do not charge for it and provided that you include this file unaltered. If you find that the program is useful, please send a payment of $25.00 to the author: William L. Sexauer, 15548 SE 175th Court, Renton, WA, 98058. Registered owners will be notified of new versions as they are developed. SYSTEM REQUIREMENTS System requirements are minimal, an IBM PC or compatible with 256K memory, dual floppy drive or single floppy drive and a hard drive, CGA or better monitor, and an X-10 PowerHouse (TM) model CP290 computer interface unit attached to COM port 1 or 2. The computer interface unit is hereafter referred to as the controller. NEW FEATURES Version 2.0 has many new features. (Thanks to all those who wrote or phoned with ideas.) The installation program, XCInstal, has been revised to save its settings, so that updating the SUNRISE.FIL data file for each year after the original installation does not require re-entry of all settings. Also, the data files used by the installation program have been renamed to .FIL extensions so that the only .DAT file(s) are your schedule file(s). If your computer clock seems to be more accurate than the X10 controller's clock, you can now have the X10 controller's clock reset each time you run the XCONTROL program. The reset only occurs when you load the schedule file (choice L from the XCONTROL main menu.) This feature is enabled by the XCInstal program if you select it. The XCONTROL program now keeps track of whether the current day is using daylight savings time. Whenever you load a schedule file to the X10 controller (choice L from the XCONTROL main menu) the program will check to see if daylight savings time is supposed to be used for the current date, and will ask you if you want to update both the computer's DOS clock and the X10 controllers clock on the first day of daylight saving time and the first day after daylight saving time. (If your computer has a battery backed up clock that is not reset with the DOS TIME command, that clock will not be reset by XCONTROL. You must run whatever utility you would normally use to copy the DOS time into the battery backed up clock.) The XCONTROL command line now accepts a schedule file name as well as a single command. This makes it possible to load a temporary schedule from the command line, XCONTROL L VACATION.DAT for example. A new unit code of 99 has been added. This code represents all devices so that it is possible to turn off everything at once. The program now supports monochrome monitors. (I don't know about Hercules graphics cards, I don't have one and can't try it out.) The program has been modified to find data files (.DAT, .ERR, .FIL and .INI) in the current directory, in any directory listed in an environment variable named XCTL, or in any directory in your PATH. This allows you to keep your schedule files in a directory other than the one that the program is in. BUG FIXES Version 1 had several bugs which have been fixed in version 2.01. The installation program didn't always compute the local sunrise and sunset times correctly, but should now. Version 1 also had some errors in the communication between the computer and the X10 controller; these errors only affected some users. I have corrected the code so that it works more reliably. INSTALLATION - FLOPPY DISC SYSTEMS The first step should be to make a backup copy of the distribution disc. You will then need three more blank discs. Label one of them XCONTROL PROGRAM DISC, the second one XCONTROL EDIT/INSTALL DISC, and the third one XCONTROL SCHEDULE FILES. Copy the files onto the three discs as follows: XCONTROL PROGRAM XCONTROL EDIT/INSTALL SCHEDULE DISK DISK DISK BASIC.ERR BASIC.ERR SAMPLE.DAT XCONTROL.ERR XCEDIT.ERR XCONTROL.EXE XCINSTAL.ERR XCEDIT.EXE XCINSTAL.EXE CITIES.FIL XCINSTAL.FIL At this point, you should have the proper program files on the proper discs. Enter SET XCTL=B:\. This will tell the XCONTROL programs where to find your schedule file(s). The next step is to create the files XCONTROL.INI and SUNRISE.FIL using the XCINSTAL program. Put the XCONTROL EDIT/INSTALL DISC in the A drive, put the XCONTROL SCHEDULE FILES DISC in the B drive, change to the B drive and then type A:XCINSTAL. The XCINSTAL program will create files XCONTROL.INI and SUNRISE.FIL on the B drive. (You may use different drive letters if your drives are not A and B, or if you want the programs in B and the data files in A. Make sure that you put the proper drive letter in the SET XCTL= command.) The data file installation will require your location, either by entry of your latitude and longitude or by selection of your state and city from a list. It also needs to know whether your area observes daylight saving time and, if so, when it starts and ends. For areas observing the Federal Daylight Saving Time, it will start on the first Sunday in April and end on the last Sunday in October (choice no. 1 from the menu.) The installation program will then calculate the sunrise and sunset time for each day of the year for your location. It will be accurate to about 5 minutes, excluding errors such as result from a nearby mountain range delaying sunrise or speeding sunset. I have found this to be sufficiently accurate for turning lights on and off to give my house a lived-in appearance. If your area does observe daylight saving time, you will need to run the XCInstall program each year sometime between January 1 and the first day of daylight saving time. This will update the SUNRISE.FIL to contain the proper daylight saving time data for the current year. Otherwise, you will have a few days at the beginning and end of daylight saving time where XCONTROL is an hour different than your clocks. You should put the following line into your AUTOEXEC.BAT file. SET XCTL=B:\ (use the drive letter for the drive where you intend to keep your schedule files.) This will tell the XCONTROL programs where to find your schedule file(s). To modify your schedule file(s) or to run the installation program to update the SUNRISE.FIL data file for a new year, put the XCONTROL EDIT/INSTALL disc in the A drive and the XCONTROL SCHEDULE FILES disc in the B drive. To operate the XCONTROL program and the X10 controller, put the XCONTROL PROGRAM disc in the A drive and the XCONTROL SCHEDULE FILES disc in the B drive. INSTALLATION - HARD DISC SYSTEMS The first step should be to make a backup copy of the distribution disc. Next, just copy all of the files to the directory where you wish to keep them. Then, run program XCINSTAL and follow the instructions. This will create the data files XCONTROL.INI and SUNRISE.FIL which are necessary for the XCONTROL and XCEDIT programs to operate. The data file installation will require your location, either by entry of your latitude and longitude or by selection of your state and city from a list. It also needs to know whether your area observes daylight saving time and, if so, when it starts and ends. For areas observing the Federal Daylight Saving Time, it will start on the first Sunday in April and end on the last Sunday in October (choice no. 1 from the menu.) The installation program will then calculate the sunrise and sunset time for each day of the year for your location. It will be accurate to about 5 minutes, excluding errors such as result from a nearby mountain range delaying sunrise or speeding sunset. I have found this to be sufficiently accurate for turning lights on and off to give my house a lived-in appearance. If your area does observe daylight saving time, you will need to run the XCINSTAL program each year sometime between January 1 and the first day of daylight saving time. This will update the SUNRISE.FIL to contain the proper daylight saving time data for the current year. Otherwise, you will have a few days at the beginning and end of daylight saving time where XCONTROL is an hour different than your clocks. CREATING A SCHEDULE FILE The default schedule file name is SCHEDULE.DAT. You may copy a sample from the distribution disc, or you may begin from scratch. If you wish to keep your schedule files in a different directory or on a different drive than the XCONTROL program files, you have two choices. The programs will find data files in any directory listed in your current PATH, or you may set an environment variable called XCTL. Just add a line to your AUTOEXEC.BAT file that reads: SET XCTL=C:\DATA\XCTL Of course, you may use any drive letter and directory name that you wish. (Hint: I keep all of my data files in subdirectories under the subdirectory \DATA. That way, I only have to do routine back-ups of the \DATA directory and its subdirectories. I only have to back up my entire hard disc if I have added a major new program.) Run the program XCEDIT to create and/or modify the schedule file. Select Add to program an event. I keep my schedule file sorted by adding new lines at specific line numbers, but you may just press RETURN instead of specifying a line number, this will add a new line at the end of the file. You will get a formatted entry screen. The cursor keys, tab and backtab keys may be used to move from field to field. It does not matter whether you use upper or lower case letters, the program will make all input lower case except that the initial character of each field will be set to upper case. Press RETURN only when you have filled all of the fields you intend to use, this will cause the program to examine all of your input and accept it or issue an error message(s) and ask you to correct the input data. Please note that the XCEDIT program updates the schedule file when you enter an event with no errors. Once an event has been entered, using the escape key does not cancel the edit, it simply exits to the previous menu or out of the program. Most fields are self explanatory, but a couple are briefly described here. A complete description of all of the fields is at the end of this file. FUNCTION may be On, Off or Dim. The DIM field is used only if the function is Dim; it is a number between 0 and 15 specifying the brightness of the lamp. 0 is off, 15 is full brightness. TIME must be entered in the format hh:mm. You may use a space or a zero in the first column for single digit hours, but you must use a zero for single digit minutes. For example, 05:07 and 5:07 are both valid, but 5:7 is not. Instead of entering a time, you may enter an offset from sunrise or sunset. Entries such as SR-75 or SS+22 are valid and specify that the event should occur 75 minutes before sunrise or 22 minutes after sunset. Offsets of up to 99 minutes are allowed. MODE may be Regular or Security (simply R or S is a sufficient entry.) Security mode sets the event to occur at a random time sometime during the specified hour. The minutes are ignored for the security mode, but must be entered anyway. DAYS are specified by filling one column for each day of the week desired. You may enter "M W F" for Monday, Wednesday and Friday, or you may use x's for each day. "X X X" does the same job as "M W F". You may make a comment line that does not cause any X10 devices to operate by simply leaving the day field blank. The MONTHS field may be used to limit the event to specific months. Simply enter the first and last months by using the first three letters of each, with a - (dash) in between. For example, Oct-Mar will cause the event to be scheduled only between October and March, inclusive. The following TIME LIMIT feature is extensively changed from version 1 of the XCONTROL system. Your schedule files may have to be updated if you have used this feature! The TIME LIMIT field may be used to indicate a limiting time to prevent a variable time from varying too far. This field is only used with times programmed as offsets from sunrise or sunset. The limit code format is to set a limit on how late the event may occur. The HH:MM is the limit time. The last character may be a Y or N. If it is a Y, the event will be scheduled at the limit for all times outside the limit. If it is a an N, the event will not be scheduled at all if the variable time is outside the limit. If the last character is left blank, it defaults to a Y. For example: Sr+45 and <07:30Y will schedule an event for 45 minutes after sunrise, unless sunrise is earlier than 6:45. If it is, the event is schedule to occur at 7:30. Another example: Ss-15 and >06:15N will schedule an event for 15 minutes before sunset, unless sunset is after 6:30. If it is, the event is not scheduled at all. RUNNING THE XCONTROL PROGRAM Simply type XCONTROL to run the program. You will get a menu of possible functions. If no function is specified on the command line, the menu will be presented. At the completion of any function, the menu will return. The XCONTROL program reads three data files and uses the information from them to download a set of event programs to a Powerhouse X10 (TM) controller. The data files are XCONTROL.INI, SUNRISE.FIL and SCHEDULE.DAT. The XCONTROL.INI file contains the settings for your customized installation. These include your comm port number, your lattitude and longitude, etc. It also contains a flag indicating whether the current date is or is not using daylight savings time. This file is created by the XCINSTAL program during initial installation. The SUNRISE.FIL file contains the approximate sunrise and sunset times. This file is also created by the XCINSTAL program. The SCHEDULE.DAT file contains the list of events that you wish to have programmed in the X10 controller. The events are stored in the controller by line number of the file, not by unit number. However, the XCONTROL program will clear all events not listed in the file. The SCHEDULE.DAT file may be updated by using the XCEDIT program. Other filenames may be used if desired. (I use a separate file called VACATION.DAT for the Christmas holiday season.) The XCONTROL program updates the events which are scheduled based on sunrise or sunset whenever the L (load controller) function is used. It is not a memory resident program that will automatically update the times. I find that running it about once a week is adequate. You don't need to revise the schedule file, just type XCONTROL L daily, weekly or whenever you wish. It will also ask you if you want to adjust both your computer clock and the X10 controller's clock whenever you load your schedule file and the program detects that daylight saving time has started or ended since the last time you loaded the schedule file. This feature is disabled when you run the program from the command line, such as the command "XCONTROL L" in a batch file. This prevents the program from asking you a question when you are not at the computer when the program runs. RUNNING THE XCONTROL PROGRAM FROM A BATCH FILE You may enter a schedule file name on the command line, with or without a command. If a command is entered on the command line, the XCONTROL program will perform that single command and then terminate. This makes it easy to run from a batch file. A batch file containing the line XCONTROL L will load the contents of the schedule file SCHEDULE.DAT into the CP290 controller. Similarly, entering the line XCONTROL L VACATION will load the contents of file VACATION.DAT into the CP290 controller. The .DAT file extension need not be entered unless you have no command and have a single character schedule file name. XCONTROL R will display the X10 controller schedule, it will not load a schedule file named R.DAT. However, XCONTROL R.DAT will load a schedule file named R.DAT, and XCONTROL L R will both load the schedule file R.DAT and download it to the X10 controller. (I use XCONTROL L VACATION so that I can sleep in on holidays.) SCHEDULE FILE FORMAT The format of the schedule file is provided for those who wish to use another editor, you don't need to worry about it if you plan on using the XCEDIT program to maintain your schedule file(s). The format is as follows. Column 1 contains the housecode of the device to be programmed. This must be a letter in the range of A to P. Column 2 should be blank. Columns 3-4 contain the unit code of the device to be programmed. Unit code 99 will operate all devices for the housecode on that line. Columns 5-30 are a description of the unit to be programmed. Columns 31-33 are the function code. ON, OFF and D (dim) are the allowed codes. If D is entered, it must be followed by a number from 0 to 15 representing the desired brightness level. 0 is full dim, or off; while 15 is fully bright. Column 34 should be blank. Columns 35-39 are the time to be programmed. Two formats are possible. The first format is HH:MM, where HH is the hour (1-12) and must have a leading space if both columns are not used. The minutes may be 00 to 59. The second format is SR+MM, where SR may be used to indicate sunrise or SS may be used for sunset. The + indicates that the minutes following are to be added to the sunrise or sunset time, while a - would subtract the minutes from the sunrise or sunset. The minutes in this case may vary from 00 to 99. For example, SR+15 would indicate 15 minutes after sunrise. Column 40 should be blank. Columns 41-42 must be either AM or PM. Column 43 is blank. Columns 44-50 may be used to set a limiting time to prevent a variable time from varying too far. A < sign denotes that the time in columns 45-49 is the earliest time that may be programmed. For example, < 4:40 indicates that the event will occur no earlier than 4:40. A > sign denotes that the time in columns 45-49 is the latest time that the event may be programmed. A final character of Y (or blank) indicates that the event will be programmed at the limit time if the computed variable time is outside the limit. A final character of N means that the event will not be programmed for times outside the limit. For example, an entry of > 7:00N for a limit on a light scheduled with respect to sunrise would mean that if the sunrise is sufficiently late that the light would be turned on after 7:00, it will not be turned on at all. Similarly, an entry of < 4:40Y (or < 4:40 ) for a sunset scheduled lamp means that if the sunset is so early that the lamp should come on before 4:40 PM, it won't come on until 4:40. Note! This feature has been revised since version 1. Your schedule files should be modified if you used the time limit feature. Columns 51-59 are the mode. Allowable entries are REGULAR, SECURITY, or blank. A blank mode will clear the event in the X10 controller. Column 60 is blank. Columns 61-67 are the days. Column 61 is M for Monday if the event is to be scheduled, otherwise it is blank. Similarly, columns 62-67 contain T W T F S S or blanks. Since it is the position of the character which is important, not its value, the use of T for both Tuesday and Thursday is not a problem. Similarly with the letter S. When using the XCEDIT program to add or revise an event, you may simply enter an X in the columns desired. The XCEDIT program will put the proper letters in the output file. If you leave all of the days blank, you will have a comment line in your file that shows all of the data but has no effect on the CP290 controller. Column 68 is blank. Columns 69-75 may be used to limit the event to particular months. Examples are: DEC-DEC would only be programmed during December. APR- JUN would be programmed during April through June. OCT-FEB would be programmed during October through December AND January through February. Columns 76-77 should contain a carriage return and line feed. It is critical that every line in the file be EXACTLY 77 characters long (or 75 text characters plus the carriage return and line feed.) The program WILL NOT operate correctly with any other line length. The file is an ASCII file and may be modified with any word processor that will allow keeping the fixed length lines. However, use of the XCEDIT program will be the most convenient method of updating the schedule files. I hope that this program is useful to you. If you have any questions or suggested improvements, please let me know. William L. Sexauer 15548 SE 175th Ct. Renton, Washington, 98058 ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of Public (software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. PsL cannot debug pro- programs over the telephone, though we can answer questions. Disks in the PsL are updated monthly, so if you did not get this disk directly from the PsL, you should be aware that the files in this set may no longer be the current versions. Also, if you got this disk from another vendor and are having prob- lems, be aware that some files may have become corrupted or lost by that vendor. Get a current, working disk from PsL. For a copy of the latest monthly software library newsletter and a list of the 3,000+ disks in the library, call or write Public (software) Library P.O.Box 35705 - F Houston, TX 77235-5705 Orders only: 1-800-2424-PSL MC/Visa/AmEx/Discover Outside of U.S. or in Texas or for general information, Call 1-713-524-6394 PsL also has an outstanding catalog for the Macintosh.